/*
 * Copyright 2010 Kevin L'Huillier <klhuillier@gmail.com>
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.lhuillier.pwsafe.io.codec;


import java.util.Date;
import java.util.UUID;


/**
 * Converts binary data to Java primitives and objects.
 */
public interface BinConverter {
    /**
     * Reads a 32-bit, little-endian integer.
     */
    int readInt(byte[] data);
    /**
     * Reads a 32-bit, little-endian integer.
     */
    int readInt(byte[] data, int offset);
    /**
     * Reads a 16-bit, little-endian short.
     */
    short readShort(byte[] data);
    /**
     * Reads a 16-bit, little-endian short.
     */
    short readShort(byte[] data, int offset);
    /**
     * Returns a timestamp from a 32-bit, little-endian unsigned value
     * representing the number of seconds since epoch, 1970-01-01T00:00
     * <p>
     * Local time is stored, not UTC. (The Password Safe documentation
     * incorrectly states that it uses GMT time.)
     */
    Date readTime32(byte[] data);
    /**
     * Returns a timestamp from a 32-bit, little-endian unsigned value
     * representing the number of seconds since epoch, 1970-01-01T00:00
     * <p>
     * Local time is stored, not UTC. (The Password Safe documentation
     * incorrectly states that it uses GMT time.)
     */
    Date readTime32(byte[] data, int offset);
    /**
     * Reads a UTF-8 string.
     */
    String readString(byte[] data);
    /**
     * Reads a UTF-8 string.
     */
    String readString(byte[] data, int offset, int length);
    /**
     * Reads a UUID. The bytes are in order as it would be read
     * left-to-right.
     */
    UUID readUuid(byte[] data);
    /**
     * Reads a UUID. The bytes are in order as it would be read
     * left-to-right.
     */
    UUID readUuid(byte[] data, int offset);
    /**
     * Translates hexadecimal digits to int values. The argument must contain an
     * even number of hex digits. The resulting ints will be in the same
     * order as the argument.
     */
    int[] hexToIntArray(byte[] data);
    /**
     * Translates hexadecimal digits to int values. The argument must contain an
     * even number of hex digits. The resulting ints will be in the same
     * order as the argument.
     */
    int[] hexToIntArray(byte[] data, int offset, int length);
    /**
     * Creates a byte array from a range within a larger byte array.
     */
    byte[] slice(byte[] data, int offset, int length);
    /**
     * Promotes a byte to an int as though it were an unsigned byte. That is,
     * -1 will become 255 (0x000000ff) instead of remaining -1.
     */
    int byteToInt(byte b);

    /**
     * Writes a UTF-8 string's bytes.
     */
    byte[] writeString(String value);
    /**
     * Writes a byte as 2 hexadecimal digits.
     */
    byte[] writeByteToHex(byte value);
    /**
     * Writes a 16-bit short in little-endian order.
     */
    byte[] writeShort(short value);
    /**
     * Writes a short as 4 hexadecimal digits in big-endian order.
     */
    byte[] writeShortToHex(short value);
    /**
     * Writes a 32-bit int in little-endian order.
     */
    byte[] writeInt(int value);
    /**
     * Writes an int as 8 hexadecimal digits in big-endian order.
     */
    byte[] writeIntToHex(int value);
    /**
     * Writes a timestamp as a little-endian, 32-bit integer representing
     * the number of seconds since epoch, 1970-01-01T00:00
     * <p>
     * Local time is stored, not UTC. (The Password Safe documentation
     * incorrectly states that it uses GMT time.)
     */
    byte[] writeTime32(Date value);
    /**
     * Writes a UUID. The bytes are in order as it would be read left-to-right.
     */
    byte[] writeUuid(UUID value);

}
